docs/development/Atomic Barrier.md

   1 # Atomic Barrier Warning
   2
   3 If GCC is upgraded and a warning appears when compiling then the generated asm source must be verified.
   4
   5 e.g.
   6 ```
   7 %% serial_softserial.c
   8 warning "Please verify that ATOMIC_BARRIER works as intended"
   9 ```
  10
  11 To perform the verification, proceed as per discusson on issue #167 which reads:
  12
  13 I hope it's enough to check that optimized-away variable still has cleanup code at end of scope.
  14
  15 ```
  16 static int markme=0;
  17 markme++;
  18 ATOMIC_BLOCK_NB(0xff) {
  19    ATOMIC_BARRIER(markme);
  20    markme++;
  21 };
  22 markme++;
  23 ```
  24
  25 pass `-save-temps=obj` (or `-save-temps=cwd`, but lots of files will end up in same directory as makefile) to gcc link step (LTO is in use), find resulting `*.ltrans*.ltrans.s` (grep for `markme`, on linux it ends up in `/tmp`) and check that generated assembly sequence is:
  26
  27 ```
  28                  MSR basepri_max, r3
  29 # (possibly markme address load)
  30                 # barier (markme) start
  31
  32 # (increment markme, load and store to memory)
  33         ldr     r2, [r3]
  34         adds    r0, r2, #1
  35         str     r0, [r3]
  36
  37                 # barier(markme)  end
  38                 MSR basepri, r3
  39
  40 # (markme value should be cached in register on next increment)
  41 ```
  42
  43 The # barrier(markme) must surround access code and must be inside MSR basepri instructions ..
  44
  45 Similar approach is used for ATOMIC_BLOCK in avr libraries, so gcc should not break this behavior.
  46
  47 IMO attribute(cleanup) and asm volatile is defined in a way that should guarantee this.
  48
  49 attribute(cleanup) is probably safer way to implement atomic sections - another possibility is to explicitly place barriers in code, but that can (and will eventually) lead to missed barrier/basepri restore on same path creating very hard to find bug.
  50
  51 The MEMORY_BARRIER() code can be omitted and use ATOMIC_BLOCK with full memory barriers, but IMO it is better to explicitly state what memory is protected by barrier and gcc can use this knowledge to greatly improve generated code in future.